Troubleshooting

This section describes the main issues related to the use of Cash-out, their possible causes, and how to resolve them.

The API handles transactions in two stages:

Synchronous Errors: Problems identified immediately during the request validation.
Asynchronous Errors: Problems identified during the processing flow, after the initial request was accepted. These are communicated via Webhooks.

1. Synchronous Errors

Synchronous errors occur at the exact moment you send the HTTP request to the API. If any validation fails (e.g., missing fields, invalid format, or authentication issues), the API returns an HTTP error code (such as 400 Bad Request or 401 Unauthorized) with an error payload.

Common Synchronous Causes:

Missing required headers or fields in the JSON body.
Invalid Pix key format or invalid bank account data.
Payload structure does not match the API specification.

Synchronous Error Payload Example

When a synchronous error occurs, the API returns a standardized JSON structure. Below is a common example of a 422 Unprocessable Entity error:

{
    "title": "Please refer to the errors property for additional details.",
    "status": 422,
    "code": "START_PAYMENT_NOT_FOUND",
    "errors": [
        "Não foi encontrado uma inicialização de pagamento com este ID."
    ]
}

code: A brief summary or identifier of the error.
errors: An array containing a short description of the specific validation failures.

Unclear Errors?

In cases where the error message returned in the response body is not clear enough, we recommend double-checking the request Headers you sent (such as your idempotencyKey, x-delfinance-account-id, etc.) to ensure they are valid and correctly formatted.

Solution:

Check the API documentation for the specific endpoint, ensure all required fields are correctly shaped, and verify your credentials. If the error persists, review the code and errors fields in the HTTP response for specific guidance.

2. Asynchronous Errors (Webhooks)

Asynchronous errors occur after the API has initially accepted your request (returning a 202 Accepted or similar success code) and transition the transaction to a processing state. During the execution phase, if an issue is found, a webhook event is dispatched to your configured endpoint.

For Cash-out errors, you will receive an event of type PIX_PAYMENT_ERROR with the status PIX_ERROR. Pay close attention to the error.code provided in the payload.

Below are the most common asynchronous errors.

2.1. DEL01: Insufficient Balance

Webhook Example

{
    "amount": 100.00,
    "eventType": "PIX_PAYMENT_ERROR",
    "status": "PIX_ERROR",
    "error": {
        "code": "DEL01",
        "description": "Saldo insuficiente."
    },
    "correlationId": null,
    "createdAt": "2023-10-27T10:00:00Z",
    "description": "Payment to supplier",
    "idempotencyKey": "a1b2c3d4-e5f6-7890-1234-56789abcdef0",
    "endToEndId": "E12345678202310271000abcdefghij",
    "finishedAt": "2023-10-27T10:00:05Z",
    "beneficiary": { ... },
    "payer": { ... }
}

Cause

The cash-out account does not have enough available balance to cover the transfer amount.

Solution

Check your Delfinance account balance. Add funds to the account if necessary, and then initiate a new transfer request.

2.2. DEL02: Insufficient Limit

Webhook Example

{
    "amount": 5000.00,
    "eventType": "PIX_PAYMENT_ERROR",
    "status": "PIX_ERROR",
    "error": {
        "code": "DEL02",
        "description": "Limite insuficiente."
    },
    "correlationId": null,
    "createdAt": "2023-10-27T10:00:00Z",
    "description": "Payment to supplier",
    "idempotencyKey": "a1b2c3d4-e5f6-7890-1234-56789abcdef0",
    "endToEndId": "E12345678202310271000abcdefghij",
    "finishedAt": "2023-10-27T10:00:05Z",
    "beneficiary": { ... },
    "payer": { ... }
}

Cause

The transfer amount exceeds the operational Usage Limits configured for your account (either the individual transaction limit or the accumulated daily/nightly limit).

Solution

Consult your current Usage Limits. If needed, request a limit increase through the configured API endpoints or the Delfinance portal. Once approved, retry the transfer.

2.3. DEL03: Blocked by Security Criteria

Webhook Example

{
    "amount": 1500.00,
    "eventType": "PIX_PAYMENT_ERROR",
    "status": "PIX_ERROR",
    "error": {
        "code": "DEL03",
        "description": "Transferência bloqueada devido a critérios de segurança."
    },
    "correlationId": null,
    "createdAt": "2023-10-27T10:00:00Z",
    "description": "Payment to supplier",
    "idempotencyKey": "a1b2c3d4-e5f6-7890-1234-56789abcdef0",
    "endToEndId": "E12345678202310271000abcdefghij",
    "finishedAt": "2023-10-27T10:00:05Z",
    "beneficiary": { ... },
    "payer": { ... }
}

Cause

The transaction was interrupted due to internal security criteria.

Solution

If you believe this block is unjustified, please contact Delfinance support providing the necessary IDs (such as endToEndId and idempotencyKey) and information for investigation.

Usage Limit Errors

Errors related to usage limits are returned following a standard nomenclature, which helps identify the service and the type of limit that was exceeded. The error code format is:

UL + [Service Acronym] + [Limit Code]

Service Acronyms

PIX: Pix
TED: External Transfer (TED)
TFI: Internal Transfer
BIL: Payment

Limit Codes

001: Daily
002: Monthly
003: Nighttime
004: Per Transaction
005: Per Nighttime Transaction

Examples:

ULPIX001: Daily limit for the Pix service exceeded.
ULTED004: Per Transaction limit for the TED service exceeded.

Useful Information for Support

If you need to open a support ticket regarding a Cash-out failure, please provide:

The endToEndId of the transaction
The idempotencyKey used
Timestamp of the transfer attempt
Account ID
The returned error Payload or Webhook body

Appendix: SPI Direct Errors

In addition to the specific errors mapped by Delfinance, transactions may be canceled directly by the Central Bank's Instant Payment System (SPI) or by the receiving participant. When this happens, the Webhook will forward the generic error code returned by the SPI so you can identify the exact reason for the failure.

The most common SPI errors include:

Code	Description
AC03	Non-existent or invalid receiver account number.
AB03	Transaction settlement interrupted due to a timeout in the SPI.
AC06	The receiver's transactional account is blocked.
AC07	The receiver's transactional account has been closed.
AC14	Incorrect account type for the receiver's transactional account.
DS04	Pix rejected by the receiver's participating institution.
AG03	Transaction type is not supported/authorized on the receiver's account (e.g., transfer to a salary account).
ED05	Instant payment processing error (generic error).
AM02	Payment/return order amount exceeds the allowed limit for the credited transactional account type.
JDPISPI015	Transactional limit validation failed for the amount (fixed block constraint applied for security to individuals and companies).

1. Synchronous Errors

Common Synchronous Causes:​

Synchronous Error Payload Example​

Solution:​

2. Asynchronous Errors (Webhooks)

2.1. DEL01: Insufficient Balance​

Webhook Example​

Cause​

Solution​

2.2. DEL02: Insufficient Limit​

Webhook Example​

Cause​

Solution​

2.3. DEL03: Blocked by Security Criteria​

Webhook Example​

Cause​

Solution​

Usage Limit Errors​

Service Acronyms​

Limit Codes​

Useful Information for Support​

Appendix: SPI Direct Errors​

Common Synchronous Causes:

Synchronous Error Payload Example

Solution:

2.1. DEL01: Insufficient Balance

Webhook Example

Cause

Solution

2.2. DEL02: Insufficient Limit

Webhook Example

Cause

Solution

2.3. DEL03: Blocked by Security Criteria

Webhook Example

Cause

Solution

Usage Limit Errors

Service Acronyms

Limit Codes

Useful Information for Support

Appendix: SPI Direct Errors